'\" t
.\"     Title: \fBmysqlslavetrx\fR
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 01/14/2017
.\"    Manual: MySQL Utilities
.\"    Source: MySQL 1.6.4
.\"  Language: English
.\"
.TH "\FBMYSQLSLAVETRX\FR" "1" "01/14/2017" "MySQL 1\&.6\&.4" "MySQL Utilities"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
mysqlslavetrx \- Slave transaction skip utility
.SH "SYNOPSIS"
.HP \w'\fBmysqlslavetrx\ \-\-gtid\-set=\fR\fB\fIGTID_SET\fR\fR\fB\ \-\-slaves=\fR\fB\fISLAVES\fR\fR\ 'u
\fBmysqlslavetrx \-\-gtid\-set=\fR\fB\fIGTID_SET\fR\fR\fB \-\-slaves=\fR\fB\fISLAVES\fR\fR
.SH "DESCRIPTION"
.PP
This utility allows users to skip multiple transactions on slaves in a single step for gtid\-enabled servers\&. In particular, it injects empty transactions on all specified slaves for each GTID in the specified GTID set\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
Skipping transactions can be useful to recover from erroneous situations that can occur during the replication process\&. However, this technique must be applied with extreme caution and full knowledge of its consequences because it might lead to data inconsistencies between the replication servers\&.
.PP
For example, let\*(Aqs consider that a transaction that inserts some data \*(Aqrow1\*(Aq into table \*(Aqt1\*(Aq fails on \*(Aqslave1\*(Aq\&. If that transaction is simply skipped to quickly resume replication on \*(Aqslave1\*(Aq without any additional intervention, then \*(Aqrow1\*(Aq is missing from that slave\&. Moreover, \*(Aqrow1\*(Aq is no longer replicated from the master since the GTID for the skipped transaction is associated to an empty transaction\&. As a consequence, the data for table \*(Aqt1\*(Aq on \*(Aqslave1\*(Aq is inconsistent with the one on the master and other slaves because \*(Aqrow1\*(Aq is missing\&. For this reason, we should make sure that the technique to skip transactions is applied in the right situations and that all additional operations to keep the data consistent are also taken\&.
.sp .5v
.RE
.PP
Skipping transactions is also useful to ignore errant transactions on slaves in order to avoid those transactions from being replicated if a failover occurs\&. For example, consider that some transactions with custom data changes were accidentally committed on a slave without turning off binary logging, and that those changes are specific to that slave and should not be replicated (e\&.g\&., additional data for reporting purposes, data mining, or local administrative commands)\&. If that slave becomes the new master as a result of a failover or switchover, then those errant transactions start being replicated across the topology\&. In order to avoid this situation, errant transactions should be skipped on all slaves\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
An errant transaction is a transaction that exists on a slave but not on all of the slaves connected to the master\&. An errant transaction has a GTID associated with the UUID of the slave to which it was committed\&. These type of transactions can result from write operations performed on the slave while binary logging is enabled\&. By nature, these transactions should not be replicated\&.
.PP
It is considered poor practice to execute write operation on slave with binary logging enabled because it creates errant transactions that can lead to unstable topologies in failover scenarios\&. The best way to deal with errant transactions is to avoid writing or applying query statements to the slave directly without turning off binary logging first\&.
.sp .5v
.RE
.PP
There are other situations like provisioning and scale out where injecting empty transaction can be a useful technique\&. See
\m[blue]\fBUsing GTIDs for Failover and Scaleout\fR\m[]\&\s-2\u[1]\d\s+2, for more information about this scenario\&.
.PP
Users must specify the set of GTIDs for the transactions to skip with the
\fB\-\-gtid\-set\fR
option, and the server connection parameters for the list of target slaves using the
\fB\-\-slaves\fR
option\&.
.PP
The utility displays the GTID set that is effectively skipped for each slave\&. If any of the specified GTIDs correspond to an already committed transaction on a slave, then those GTIDs are ignored for that slave (not skipped) because no other transaction (empty or not) can be applied with the same GTID\&. Users can execute the utility in dry run mode using the
\fB\-\-dryrun\fR
option to confirm which transactions would be skipped with the provided input values without effectively skipping them\&.
.PP
The utility does not require replication to be stopped\&. However, in some situations it is recommended\&. For example, in order to skip a transaction from the master on a slave, that slave should be stopped otherwise the target transaction might be replicated before the execution of the skip operation and therefore not skipped as expected\&.
.PP
Users can also use the
\fB\-\-verbose\fR
option to see additional information when the utility executes\&. This includes a list of slaves not supporting GTIDs and the GTIDs of the injected transactions\&.
OPTIONS.PP
\fBmysqlslavetrx\fR
accepts the following command\-line options:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-dryrun
.sp
Execute the utility in dry\-run mode, show the transactions (GTID) that would have been skipped for each slave but without effectively skipping them\&. This option is useful to verify if the correct transactions are skipped\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-gtid\-set=\fIgtid\-set\fR
.sp
Set of Global Transaction Identifiers (GTID) to skip\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-help
.sp
Display a help message and exit\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-license
.sp
Display license information and exit\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-slaves=\fIslaves_connections\fR
.sp
Connection information for slave servers\&. List multiple slaves in comma\-separated list\&.
.sp
To connect to a server, it is necessary to specify connection parameters such as the user name, host name, password, and either a port or socket\&. MySQL Utilities provides a number of ways to supply this information\&. All of the methods require specifying your choice via a command\-line option such as \-\-server, \-\-master, \-\-slave, etc\&. The methods include the following in order of most secure to least secure\&.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Use login\-paths from your
\&.mylogin\&.cnf
file (encrypted, not visible)\&. Example :
\fIlogin\-path\fR[:\fIport\fR][:\fIsocket\fR]
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Use a configuration file (unencrypted, not visible) Note: available in release\-1\&.5\&.0\&. Example :
\fIconfiguration\-file\-path\fR[:\fIsection\fR]
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Specify the data on the command\-line (unencrypted, visible)\&. Example :
\fIuser\fR[:\fIpasswd\fR]@\fIhost\fR[:\fIport\fR][:\fIsocket\fR]
.RE
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-ssl\-ca
.sp
The path to a file that contains a list of trusted SSL CAs\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-ssl\-cert
.sp
The name of the SSL certificate file to use for establishing a secure connection\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-ssl\-key
.sp
The name of the SSL key file to use for establishing a secure connection\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-ssl
.sp
Specifies if the server connection requires use of SSL\&. If an encrypted connection cannot be established, the connection attempt fails\&. Default setting is 0 (SSL not required)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-verbose, \-v
.sp
Specify how much information to display\&. Use this option multiple times to increase the amount of information\&. For example,
\fB\-v\fR
= verbose,
\fB\-vv\fR
= more verbose,
\fB\-vvv\fR
= debug\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-version
.sp
Display version information and exit\&.
.RE
NOTES.PP
The path to the MySQL client tools should be included in the PATH environment variable in order to use the authentication mechanism with login\-paths\&. This permits the utility to use the my_print_defaults tools which is required to read the login\-path values from the login configuration file (\&.mylogin\&.cnf)\&.
LIMITATIONS.PP
The utility requires all target slaves to support global transaction identifiers (GTIDs) and have
gtid_mode=ON\&.
EXAMPLES.PP
Skip multiple GTIDs on the specified slaves:
.sp
.if n \{\
.RS 4
.\}
.nf
shell> \fBmysqlslavetrx \-\-gtid\-set=af6b22ee\-7b0b\-11e4\-aa8d\-606720440b68:7\-9 \e\fR
          \fB\-\-slaves=user:pass@localhost:3311,user:pass@localhost:3312\fR
WARNING: Using a password on the command line interface can be insecure\&.
#
# GTID set to be skipped for each server:
# \- localhost@3311: af6b22ee\-7b0b\-11e4\-aa8d\-606720440b68:7\-9
# \- localhost@3312: af6b22ee\-7b0b\-11e4\-aa8d\-606720440b68:7\-9
#
# Injecting empty transactions for \*(Aqlocalhost:3311\*(Aq\&.\&.\&.
# Injecting empty transactions for \*(Aqlocalhost:3312\*(Aq\&.\&.\&.
#
#\&.\&.\&.done\&.
#
.fi
.if n \{\
.RE
.\}
.PP
Execute the utility in dryrun mode to verify which GTIDs would have been skipped on all specified slaves:
.sp
.if n \{\
.RS 4
.\}
.nf
shell> \fBmysqlslavetrx \-\-gtid\-set=af6b22ee\-7b0b\-11e4\-aa8d\-606720440b68:6\-12 \e\fR
          \fB\-\-slaves=user:pass@localhost:3311,user:pass@localhost:3312\fR
          \fB\-\-dryrun\fR
WARNING: Using a password on the command line interface can be insecure\&.
#
# WARNING: Executing utility in dry run mode (read only)\&.
#
# GTID set to be skipped for each server:
# \- localhost@3311: af6b22ee\-7b0b\-11e4\-aa8d\-606720440b68:6:10\-12
# \- localhost@3312: af6b22ee\-7b0b\-11e4\-aa8d\-606720440b68:6:10\-12
#
# (dry run) Injecting empty transactions for \*(Aqlocalhost:3311\*(Aq\&.\&.\&.
# (dry run) Injecting empty transactions for \*(Aqlocalhost:3312\*(Aq\&.\&.\&.
#
#\&.\&.\&.done\&.
#
.fi
.if n \{\
.RE
.\}
.PP
Skip multiple GTIDs on the specified slaves using the verbose mode:
.sp
.if n \{\
.RS 4
.\}
.nf
shell> \fBmysqlslavetrx \-\-gtid\-set=af6b22ee\-7b0b\-11e4\-aa8d\-606720440b68:6\-12 \e\fR
          \fB\-\-slaves=user:pass@localhost:3311,user:pass@localhost:3312\fR
          \fB\-\-verbose\fR
WARNING: Using a password on the command line interface can be insecure\&.
#
# GTID set to be skipped for each server:
# \- localhost@3311: af6b22ee\-7b0b\-11e4\-aa8d\-606720440b68:6:10\-12
# \- localhost@3312: af6b22ee\-7b0b\-11e4\-aa8d\-606720440b68:6:10\-12
#
# Injecting empty transactions for \*(Aqlocalhost:3311\*(Aq\&.\&.\&.
# \- af6b22ee\-7b0b\-11e4\-aa8d\-606720440b68:6
# \- af6b22ee\-7b0b\-11e4\-aa8d\-606720440b68:10
# \- af6b22ee\-7b0b\-11e4\-aa8d\-606720440b68:11
# \- af6b22ee\-7b0b\-11e4\-aa8d\-606720440b68:12
# Injecting empty transactions for \*(Aqlocalhost:3312\*(Aq\&.\&.\&.
# \- af6b22ee\-7b0b\-11e4\-aa8d\-606720440b68:6
# \- af6b22ee\-7b0b\-11e4\-aa8d\-606720440b68:10
# \- af6b22ee\-7b0b\-11e4\-aa8d\-606720440b68:11
# \- af6b22ee\-7b0b\-11e4\-aa8d\-606720440b68:12
#
#\&.\&.\&.done\&.
#
.fi
.if n \{\
.RE
.\}
.sp
PERMISSIONS REQUIRED.PP
The user used to connect to each slave must have the required permissions to inject empty transactions, more precisely the SUPER privilege is required to set the
gtid_next
variable\&.
.SH "COPYRIGHT"
.br
.PP
Copyright \(co 2006, 2017, Oracle and/or its affiliates. All rights reserved.
.PP
This documentation is free software; you can redistribute it and/or modify it only under the terms of the GNU General Public License as published by the Free Software Foundation; version 2 of the License.
.PP
This documentation is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
.PP
You should have received a copy of the GNU General Public License along with the program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA or see http://www.gnu.org/licenses/.
.sp
.SH "NOTES"
.IP " 1." 4
Using GTIDs for Failover and Scaleout
.RS 4
\%http://dev.mysql.com/doc/refman/5.7/en/replication-gtids-failover.html
.RE
.SH "SEE ALSO"
For more information, please refer to the MySQL Utilities and Fabric
documentation, which is available online at
http://dev.mysql.com/doc/index-utils-fabric.html
.SH AUTHOR
Oracle Corporation (http://dev.mysql.com/).
